home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / program / mkdpnd11.lha / MkDepend-1.1 / MkDepend.doc < prev    next >
Text File  |  1995-10-14  |  10KB  |  297 lines
  1. $VER: MkDepend:doc 1.1 (13-Oct-95)
  2.  
  3.                                  MkDepend 1.1
  4.  
  5.                        Copyright © 1995 by Lars Düning
  6.                              All Rights Reserved.
  7.                   Permission granted for non-commercial use.
  8.  
  9.  
  10. Introduction
  11. ------------
  12.   Makefiles are very useful in the development of larger program systems,
  13.   as they notate the various dependencies and associated needed actions
  14.   in a machine-useable notation. Unfortunately it's the most important
  15.   dependency between C sources and their includes which have to be
  16.   maintained by hand, a most boring and errorprone task. MkDepend is one
  17.   of those programs which attempt to automate this part of development
  18.   by scanning source files for includes and repeating this step
  19.   recursively until the complete transitive closure of included files
  20.   is determined. The found dependencies are then written into an
  21.   existing makefile, keeping it up to date.
  22.  
  23.  
  24. Usage
  25. -----
  26.   MkDepend is a CLI-only program, needs at least OS 2.0 and 10 KByte stack.
  27.  
  28.   Template: -F=MAKE/K,-I=INCLUDE/K/M,-X=EXCEPT/K/M,-S=SUFFIX/K/M,
  29.             -P=OBJPAT/K/M,-V=VERBOSE/S,FILES/M
  30.  
  31.   mkdepend  {-i|INCLUDE <includepath>[::<symbol>]}
  32.             {-x|EXCEPT  <filepattern>}
  33.             {-s|SUFFIX  <src_ext>{,<src_ext>}[:<obj_ext>] | :<obj_ext>}
  34.             {-p|OBJPAT  <src_ext>{,<src_ext>}:<obj_pattern>
  35.             [-f|MAKE    <makefile>]
  36.             [-v|VERBOSE]
  37.             {<filepattern>}
  38.  
  39.  
  40.     The space between the short form of the keywords and their operands
  41.     may be omitted. For example
  42.  
  43.       mkdepend -IINCLUDE:
  44.       mkdepend -I INCLUDE:
  45.       mkdepend -I=INCLUDE:
  46.  
  47.     are equivalent.
  48.  
  49.  
  50.   MkDepend is given a 'skeleton' of C source files and searches them for
  51.   included files. The Includes found are recursively searched for includes
  52.   themselves, until the complete transitive closure has been determined.
  53.   MkDepend searches the includes first in the current directory, then in
  54.   the given paths (if any), imitating the C preprocessor's behaviour.
  55.   The files are scanned for include statements of the form
  56.  
  57.     #include "<filename>"
  58.  
  59.   excluding those which are commented out using C-style /* */- or
  60.   C++-style //-comments. Every other content of the files is ignored.
  61.  
  62.   After all includes have been found, the dependencies are written into
  63.   a makefile (creating it if necessary). The makefile is searched for
  64.   a line
  65.  
  66.     # --- DO NOT MODIFY THIS LINE -- AUTO-DEPENDS FOLLOW ---
  67.  
  68.   after which MkDepend adds the dependencies, overwriting old ones, then
  69.   terminating the dependencies with the line
  70.  
  71.     # --- DO NOT MODIFY THIS LINE -- AUTO-DEPENDS PRECEDE ---
  72.  
  73.   Text following the second tagline in the makefile is not modified.
  74.  
  75.   If the first tagline is not found, the tagged dependencies are simply
  76.   appended to the file. Existing makefiles are modified by renaming it
  77.   to <origname>.bak and then re-creating the makefile by copying the
  78.   data not to be modified.
  79.  
  80.   The found dependencies for the 'skeleton' files are written as
  81.  
  82.     <skeleton> : <included file 1> <included file 2>...
  83.  
  84.   Lines are limited to 80 chars, longer entries are folded into several
  85.   lines, ending each but the last line with a backslash (\).
  86.  
  87.   MkDepend can be teached to know about source/object file relationships
  88.   to be used in the entries written. E,g, the entry generated for a typical
  89.   C source file would be of the form
  90.  
  91.     <skeleton>.o : <skeleton>.c <include 1> <include 2> ...
  92.  
  93.   Includes appear with that path in the list under which MkDepend found
  94.   them. To support multi-platform development, replacement texts may
  95.   be specified for the paths which are then used instead in the output.
  96.  
  97.  
  98. Arguments
  99. ---------
  100.  
  101.   <filepattern>
  102.  
  103.     Any command argument not recognizable as option is considered as
  104.     specification of one of the 'skeleton' sources.
  105.     Wildcards are recognized.
  106.  
  107.     Default: #?.c
  108.  
  109.     Example:
  110.  
  111.       mkdepend #?.c #?.cc
  112.  
  113.         All files ending in ".c" or ".cc" are considered.
  114.  
  115.    ------
  116.  
  117.   -x     <filepattern>
  118.   EXCEPT <filepattern>
  119.  
  120.     Files which are not part of the 'skeleton', even if they are specified
  121.     as such.
  122.  
  123.     Example:
  124.  
  125.       mkdepend #?.c -x test#?
  126.  
  127.         All files ending in ".c", except those whose name start with "test",
  128.         are considered as sources.
  129.  
  130.    ------
  131.  
  132.   -i      <includepath>[::<symbol>]}
  133.   INCLUDE <includepath>[::<symbol>]}
  134.  
  135.      Specify a directory to be searched for include files. The paths are
  136.      searched in the order given on the command line. The current
  137.      directory is always searched first.
  138.  
  139.      If <symbol> is specified, the <includepath> is replaced by it in
  140.      the dependencies written to the makefile.
  141.  
  142.      Example:
  143.  
  144.        mkdepend -i INCLUDE:
  145.  
  146.          Include files are searched in the current directory and in INCLUDE: .
  147.  
  148.        mkdepend -I INCLUDE:pdlibs::$(PDLIBS)
  149.  
  150.          Include files are searched in the current directory and
  151.          in INCLUDE:pdlibs. A file like "INCLUDE:pdlibs/tree.h" will be
  152.          written as "$(PDLIBS)tree.h" into the makefile.
  153.  
  154.    ------
  155.  
  156.   -s     <src_ext>{,<src_ext>}[:<obj_ext>] | :<obj_ext>}
  157.   SUFFIX <src_ext>{,<src_ext>}[:<obj_ext>] | :<obj_ext>}
  158.  
  159.     Specify a name relationship between source and object files.
  160.     If a source name ends in one of the given <src_ext>s, an Makefile entry
  161.     with the object name constructed using the associated <obj_ext>.
  162.     The <obj_ext> given with no associated <src_ext> serves as default
  163.     extension used for those <src_ext> which are given without own
  164.     <obj_ext>.
  165.  
  166.     Default: -s :.o -s .c
  167.  
  168.     Example:
  169.  
  170.       mkdepend -s :.o -s .c,.cc
  171.  
  172.         Default <obj_ext> is ".obj", which is used for files with the
  173.         extension ".c" and ".cc".
  174.  
  175.    ------
  176.  
  177.   -p      <src_ext>{,<src_ext>}:<obj_pattern>
  178.   OBJPAT  <src_ext>{,<src_ext>}:<obj_pattern>
  179.  
  180.     Similar to SUFFIX, but allows more complicated name relations.
  181.     <obj_pattern> gives the object file name verbatim, using placeholders
  182.     for the actual filenames:
  183.  
  184.       %s: the full sourcename (w/o suffix)
  185.       %p: the path part of the sourcename
  186.       %[-][<][<number>]p: the path part of the sourcename
  187.         <number>: skip the first <number> directories of the path,
  188.                   defaults to 0.
  189.         <       : count the directories from the end or the path part.
  190.         -       : use, don't skip the counted directories.
  191.       %n: the base of the sourcename (w/o suffix)
  192.       %%: the character '%'.
  193.       %x: the character x for every other character.
  194.  
  195.     Example:
  196.  
  197.       mkdepend -p .c:obj/%n.o
  198.  
  199.         For every sourcefile <name>.c, an entry for obj/<name>.o is
  200.         created.
  201.  
  202.       mkdepend -p .c:obj/%1p%n.o source/#?.c
  203.  
  204.         For every sourcefile source/<name>.c, an entry for obj/<name>.o is
  205.         created.
  206.  
  207.    ------
  208.  
  209.   -f    <makefile>
  210.   MAKE  <makefile>
  211.  
  212.     Specify the makefile to modify. If not specified, MkDepend searches
  213.     in order for "Makefile", "Makefile.mk", "DMakefile" and "SMakefile".
  214.     If none of these exists, "Makefile" is used.
  215.  
  216.    ------
  217.  
  218.   -v
  219.   VERBOSE
  220.  
  221.     Print some output during operation, namely the program name and the
  222.     file currently under examination.
  223.  
  224.  
  225. Installation
  226. ------------
  227.   Copy the executable "MkDepend" into a suiting directory, profitably
  228.   into one in your search path. That's it.
  229.  
  230.  
  231. Program Information
  232. -------------------
  233.   MkDepend consists of three source files with associated includes:
  234.  
  235.     reader.c,.h: Reading of source files and scanning for #include statements.
  236.                  Copying and writing of makefiles.
  237.     nodes.c,.h : Management of the names and locations of the files analysed.
  238.                  It is implemented as a binary search tree with an addition
  239.                  linked list.
  240.     main.c     : Commandline parsing and program control.
  241.  
  242.   To recreate MkDepend, compile the three sources and link them.
  243.  
  244.   MkDepend was written for DICE 3.01, makefiles are provided for use with
  245.   DICE own dmake (`DMakefile') and Dennis Vadura's DMake (`Makefile').
  246.  
  247.  
  248. Bugs/TODO
  249. ---------
  250.   main.c is a nasty mixture of Amiga-specific and generic code.
  251.   Wildcard expansion is done using DICE' expand_files(), which does not
  252.     accept the full set of wildcards implemented by AmigaDOS.
  253.   The version number shows up verbatim in much to many files.
  254.  
  255.  
  256. Author
  257. ------
  258.   Lars Düning, Am Wendenwehr 25, 38114 Braunschweig, Germany,
  259.   duening@ibr.cs.tu-bs.de
  260.  
  261.   The file reader was inspired by the input module of lcc by David Hanson
  262.   and Christopher Fraser.
  263.  
  264.   The elaborate %p pattern follows a suggestion by Michael A. Wiedmer
  265.   (<maw@paralax.demon.co.uk>).
  266.  
  267.  
  268. Legalese
  269. --------
  270.   MkDepend is Copyright © 1995 by Lars Düning. All Rights are reserved.
  271.   Permission granted for non-commercial use.
  272.  
  273.   MkDepend may be freely distributed, provided that all copyright notices
  274.   and associated disclaimers are reproduced, and that only a reasonable
  275.   copying fee is charged. MkDepend may be included as "one program among
  276.   many" in (even commercial) software distributions.
  277.   No fee may be charged for MkDepend itself.
  278.  
  279.   MkDepend may be freely modified, provided that the modifications are
  280.   made available to the public, that each changed file carries a notice
  281.   stating who changed what and when, and that the modified versions are
  282.   clearly distinguishable from the original.
  283.  
  284.   Parts of MkDepend may be used in own (even commercial) programs provided
  285.   that proper credit is given.
  286.  
  287.   MkDepend IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  288.   WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  289.   MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  290.  
  291.  
  292. Last Words
  293. ----------
  294.   "Good informations are hard to get. It is even more difficult to put
  295.    them into use." -- Sherlock Holmes
  296.  
  297.